home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1999 Spring / macformat-077.iso / Shareware Plus / Development / SpriteWorld 2.2 / Documentation / Add-On Docs / SWFastLine < prev    next >
Encoding:
Text File  |  1998-12-24  |  7.2 KB  |  143 lines  |  [TEXT/ttxt]
  1. Introduction
  2.  
  3. SWFastLine.c contains several functions for drawing 8-bit lines very quickly (much faster than QuickDraw). All of the functions except SWDrawLine68kAsm clip the line if necessary, and some functions will even draw lines in a scrolling world. Yet others will copy a line from one Frame into another, which can be used to erase lines drawn in the work area the previous frame of the animation. Routines are also provided to draw and copy framed rectangles in both scrolling and non-scrolling SpriteWorlds.
  4.  
  5. These routines can be used for a variety of purposes. For instance, you could use SWDrawFrameRectInScrollingWorld to draw a rectangle around a Sprite, resulting in an effect similar to WarCraft when you click on units to select them. You could use SWCopyFrameRectInScrollingWorld to erase that rectangle the next frame of the animation, and then call SWDrawFrameRectInScrollingWorld again to draw it in its new position. You might call SWDrawFrameRectInScrollingWorld from the Sprite's DrawProc, or you might install a postEraseCallBack or postDrawCallBack to draw your lines and rects offscreen, as well as erase them from the previous frame.
  6.  
  7. You can also use these routines for special effects. You could use the SWCopyLine routine creatively to copy your work area to the screen when a level starts, instead of passing true to SWUpdateSpriteWorld.
  8.  
  9. To use the functions in SWFastLine.c, simply add it to your project (it's in the Utils folder), and don't forget to #include <SWFastLine.h> in your source code too.
  10.  
  11. Handling Idle Sprites
  12.  
  13. If you use any of these routines to draw a line or rectangle in the work area of your SpriteWorld, it is possible that you could draw over an idle sprite. This is especially noticeable if you erase your line the next frame, since this leaves a "hole" in the idle sprite where the line used to be. The only solution to this problem is to not use any idle sprites. If necessary, you can set each Sprite's needsToBeDrawn flag to true when its moveProc is called.
  14.  
  15. Function Parameters
  16.  
  17. All of the functions contain the following parameters. Here is their description:
  18.  
  19. dstFrameP - the Frame you want the line drawn in. Can be your SpriteWorld's windowFrameP, workFrameP, or backFrameP, or even a Sprite's FramePtr.
  20.  
  21. srcPoint and dstPoint - the beginning and end of the line
  22.  
  23. color - a value between 0 and 255 indicating the color index of the line. If you use the system palette, 0 will be white and 255 will be black, and every value in between is a different color.
  24.  
  25.  
  26. Function Reference
  27.  
  28. ---Non-Scrolling functions---
  29.  
  30. SWDrawLine68kAsm
  31.  
  32. SW_FUNC void SWDrawLine68kAsm(
  33. FramePtr dstFrameP, 
  34. Point srcPoint, 
  35. Point dstPoint, 
  36. Byte color)
  37.  
  38. This is a limited routine written in 68k assembly language that will draw lines faster than SWDrawLine. However, this function will not compile for PPC. It also draws the lines a little differently than SWDrawLine, meaning that if you use this function when compiling for 68k and SWDrawLine when compiling for PPC, your lines will look slightly different depending on whether you're running the 68k or PPC version.
  39.  
  40. Additionally, this function performs no clipping, so make sure your srcPoint and dstPoint are with the dstFrameP's frameRect! Otherwise, your program will most likely crash.
  41.  
  42.  
  43. SWDrawLine
  44.  
  45. SW_FUNC void SWDrawLine(
  46. FramePtr dstFrameP, 
  47. Point srcPoint, 
  48. Point dstPoint, 
  49. Byte color)
  50.  
  51. This is a line-drawing function written in C, so it compiles for both 68k and PPC Macs. Clipping is performed if necessary. Not for use in a scrolling world - use SWDrawLineInScrollingWorld instead.
  52.  
  53.  
  54. SWCopyLine
  55.  
  56. SW_FUNC void SWCopyLine(
  57.     FramePtr srcFrameP, 
  58.     FramePtr dstFrameP, 
  59.     Point srcPoint, 
  60.     Point dstPoint)
  61.  
  62. Mainly intended for quickly erasing lines drawn with SWDrawLine, SWCopyLine will copy the pixels of a line from srcFrameP to dstFrameP. Both frames must be the same size for clipping to work properly, since the line is only clipped to the dstFrameP.
  63.  
  64. This function can be used for other purposes besides erasing lines drawn the previous frame. For instance, you might use it to copy the offscreen area to the screen, revealing each row one line at a time.
  65.  
  66.  
  67. SWDrawFrameRect
  68.  
  69. SW_FUNC void SWDrawFrameRect(
  70.     FramePtr dstFrameP, 
  71.     Rect *dstRect, 
  72.     Byte color)
  73.  
  74. Use this function to draw a framed rectangle in a non-scrolling world. It works about like QuickDraw's FrameRect function in that the top and left sides are drawn where you specify, and the right and bottom sides are drawn one pixel to the left or one pixel above that side. This is so that if you pass a rect such as 0,0,640,480, to draw a frame around a 640x480 screen, the bottom and right sides will be drawn where they should be. (Remember that if you have 640 pixels, and the first pixel is column 0, your last pixel will be 539, or 640-1.)
  75.  
  76. Something to keep in mind is that the line routines to *not* have a similar mechanism. That is, if you draw a line from row and column 0 to row 0, column 640, the last pixel of your line will extend past your screen (on a 640x480 screen, that is), since the line routine will stop after drawing pixel 640, not pixel 639.
  77.  
  78. This may seem like an unconsistent system, but it's the way QuickDraw works, and I figured these routines should work like QuickDraw.
  79.  
  80.  
  81. SWCopyFrameRect
  82.  
  83. SW_FUNC void SWCopyFrameRect(
  84.     FramePtr srcFrameP,
  85.     FramePtr dstFrameP, 
  86.     Rect *dstRectP)
  87.  
  88. This is typically used to erase a framed rect drawn with SWDrawFrameRect the previous frame. It copies a framed rect from srcFrameP to dstFrameP.
  89.  
  90.  
  91. ---Scrolling functions---
  92.  
  93.  
  94. SWDrawLineInScrollingWorld
  95.  
  96. SW_FUNC void SWDrawLineInScrollingWorld(
  97.     SpriteWorldPtr spriteWorldP, 
  98.     FramePtr dstFrameP, 
  99.     Point srcPoint, 
  100.     Point dstPoint, 
  101.     Byte color)
  102.  
  103. This function is the same as SWDrawLine, except that it is for use in a scrolling world. (i.e. you should pass the spriteWorldP->workFrameP or spriteWorldP->backFrameP as the dstFrameP parameter).
  104.  
  105.  
  106. SWCopyLineInScrollingWorld
  107.  
  108. SW_FUNC void SWCopyLineInScrollingWorld(
  109.     SpriteWorldPtr spriteWorldP, 
  110.     FramePtr srcFrameP, 
  111.     FramePtr dstFrameP, 
  112.     Point srcPoint, 
  113.     Point dstPoint,
  114.     Rect *clipRectP)
  115.  
  116. Typically used to erase lines drawn the previous frame with SWDrawLineInScrollingWorld. Generally the srcFrameP would be the spriteWorldP->backFrameP, and the dstFrameP would be the spriteWorldP->workFrameP.
  117.  
  118. The clipRectP is a new parameter that specifies what rectangle the drawing should be clipped to. You should pass either the spriteWorldP->visScrollRect or spriteWorldP->oldVisScrollRect. Use the oldVisScrollRect if you are erasing a line from the previous frame.
  119.  
  120.  
  121. SWDrawFrameRectInScrollingWorld
  122.  
  123. SW_FUNC void SWDrawFrameRectInScrollingWorld(
  124.     SpriteWorldPtr spriteWorldP, 
  125.     FramePtr dstFrameP, 
  126.     Rect *dstRectP, 
  127.     Byte color)
  128.  
  129. Used to draw framed rectangles in a scrolling world.
  130.  
  131.  
  132. SWCopyFrameRectInScrollingWorld
  133.  
  134. SW_FUNC void SWCopyFrameRectInScrollingWorld(
  135.     SpriteWorldPtr spriteWorldP, 
  136.     FramePtr srcFrameP, 
  137.     FramePtr dstFrameP, 
  138.     Rect *dstRectP,
  139.     Rect *clipRectP)
  140.  
  141. Typically used to erase framed rects drawn with SWDrawFrameRectInScrollingWorld the previous frame. 
  142.  
  143. The clipRectP specifies what rectangle the drawing should be clipped to. You should pass either the spriteWorldP->visScrollRect or spriteWorldP->oldVisScrollRect. Use the oldVisScrollRect if you are erasing a line from the previous frame.